Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d11 / viz412.arc / VIZ.DOC < prev next >

Wrap

Text File | 1991-06-06 | 65KB | 1,265 lines

┌──────────────────────────────────────────────────────────────────────────────┐ │ Designations claimed as trademark appear in initial capitals or all capitals │ └──────────────────────────────────────────────────────────────────────────────┘ Copyright (c) 1989, 1990, 1991 by F.M. de Monasterio. All rights reserved. VIz version 4.12 ---------------- SUMMARY VIz is a small resident program that accelerates BIOS (and DOS) video input and output in text mode; it can be used with IBM-compatible MDA, EGA or VGA adapter cards and Hercules HGC and HGC+ cards. In its present version, VIz produces video interference ("snow") in old CGA cards; for such systems you can use VIz-CGA, a snow-free, 8088-cpu oriented version. In addition, VIz includes an independent, resident component for displaying a block cursor, either continously or alternating with a line cursor (at an adjustable rate of alternation). The latter display is well suited for easy localization of the cursor in some laptop screens. Finally, VIz also contains an independent, resident ANSI-filter driver that mediates a subset of the ANSI escape sequences to control the console. This filter can be used, instead of ANSI.SYS, to implement ANSI escape sequences to control video display, with the advantage that can be turned off and on, and removed from memory without rebooting. All 3 resident modules occupy a total of less than about 1700 bytes of RAM. Depending on system configuration and BIOS version, video acceleration by a factor of between 2 and 10 may be expected. ------------------------------------------------------------------------------ GENERAL INFORMATION There are 3 basic ways of producing character-oriented, text video displays in DOS computers: (1) using direct video memory mapping, which is extremely fast but dependent on the video hardware and has a limited portability; (2) via BIOS services, provided by the first "hidden" DOS boot file and usually augmented by the video adapter, which are not as fast as direct mapping but more portable; and (3) via DOS services, provided by the other "hidden" DOS boot file and sometimes augmented via installable device drivers, which are much slower than the other two approaches, but have greater portability and permit additional operations such as redirection. Many of the DOS and BIOS video services can be accelerated using a resident program that intercepts the calls made to such services, and implements the video operation with faster instructions. Because of the nature of DOS and of BIOS services, the interception must occur at the input site of the BIOS services (interrupt 10h), whereas it can occur at the input site (interrupt 21h) or output site (interrupt 29h), or both, of the DOS services. VIz is a utility that accelerates many of the basic text-video functions and permits changing the video mode, page and font of the display as well as the raw or normal mode of DOS video ouput. When used with a VGA/EGA system, VIz also permits control of the red, green, and blue mixture that determines the color of each of the 16 registers of the EGA/VGA color palette, allowing for the remapping of the RGB mixture to suit user preferences. Finally, VIz also permits the control of the frequency (pitch) of the bell's tone. VIz releases require MS-DOS or PC-IBM DOS version 2.10 or later. A 32-bit CRC calculation is performed each time VIz is invoked. If it fails, the program will abort to DOS; CRC failures indicate corruption of the code, and the program therefore should not be used. ---------------- HARDWARE COMMANDS - TESTOUT.EXE Cursor position is updated via direct hardware commands. Starting with VIz release 3.00, such commands can be sent out as WORD (double-byte) values or as two successive BYTE values. The WORD-out method of addressing, also used by other programs (e.g. Microsoft Windows), yields faster accelerations but it may not work with some (older) clone systems. To test which method of addressing you can use, run the program TESTOUT.EXE to see if the cursor appears at the indicated position. If it does so, your system can handle WORD out commands. CPU VERSIONS The 286 release of VIz is faster than the 086 release by taking advantage of 286-code in real mode. Similarly, the 386 release uses 386-code in real mode to take advantage of 32-bit operations, and other 386-specific instructions; while this combination makes this release faster than the others for a 80386 or 80486 CPU machine, its video acceleration performance is dependent on bus size (i.e. 386SX) and the additional wait states imposed during video memory access. Consequently, actual acceleration values may be less than otherwise could be expected. The same caveat applies to 80486 processors due to clock cycle differences for some instructions and their alternatives (i.e., 'lods' vs. 'mov/add' combination); a 486 release of VIz may become available soon. Average accelerations and comparisons with other accelerators, based on four benchmarks, are described in the accompanying file VIZ.DAT for 086, 286, and 386 VIz versions. ------------------------------------------------------------------------------ 1. VIDEO ACCELERATION MODULE VIz installs itself as a resident program that can be invoked repeatedly for modification of its parameters, without producing multiple copies on memory; the accelerator module of the resident uses less than 1,000 bytes of RAM. To maximize speed of code, but minimize resident size, acceleration only occurs for video page 0 in a text mode (1-3, color; 7, monochrome). In other pages or graphic modes, VIz becomes inactive and is automatically reactivated by a change that resets the video to page 0 in a text mode. Viz accelerates BIOS video functions, and it can also accelerate DOS-mediated screen output. The acceleration of VIz can be turned off either by deallocating the program with the switch /U (if no other resident has been installed after VIz) or by making it quiescent with switch /Q (i.e. it remains resident but not active) until reactivation (any switch but /QU) or deallocation by a further call to VIz. The relative acceleration depends on several factors, including BIOS version and date, 80x86 Intel CPU model and speed, and whether or not ROM video BIOS is shadowed or remapped to faster RAM. Another factor, often disregarded, is the use of other residents also intercepting the interrupt 10h. In addition, some memory managers, even when RAM-shadowing video BIOS, have been found to yield nontrivial degradations of video speed (see VIZ.DAT). Whereas smaller acceleration factors are to be expected in machines performing a faster BIOS operation (i.e. tighter ROM code, faster CPU, shadowed or remapped ROM), the relative weight of individual factors may yield unexpected results. VIz updates relevant parameters in the BIOS data area (segment 40h), such as cursor position (page 0 only) and type, video mode, page, and font, that are also processed by VIz; while such updating degrades video acceleration time, it also decreases the possibility of conflict with foreground utilities that use BIOS data but bypass BIOS calls. ---------------- 2. BLOCK-AND-LINE CURSOR ALTERNATION MODULE To help cursor visualization in screens where the cursor is not easily seen, as in some laptop displays, VIz provides a small resident module that allows for the display of a (full-)block cursor, either continuously or alternating with a line cursor. The alternation rate can be adjusted in steps of 54.9 ms between about 0.055 s (/V1) and 5.5 s (/V99). A zero alternation rate (/V0) produces a continously present block cursor. For the module to be loaded in memory, VIz must be installed with any /V switch (see below), and it adds an additional 100 bytes to the resident size of VIz. Very short or very long alternation rates are distracting or hard to follow. When selecting a rate for laptop displays, start with a value of n=9 (.50 s) or so. Block cursor alternation can be turned off by making this resident quiescent with the switch /V+ (until its reactivation with /Vn). All cursor operations use direct commands to the hardware, and assume register-level compatibility with the Motorola 6845 CRT controller. This chip is present in MDA, CGA, and HGC cards, while a 6845-compatible CRTC is a custom LSI chip in the IBM-EGA, part of the Memory Controller Gate Array on the MCGA, or a part of the Video Graphics Array on the VGA. Notice that the hardware-controlled blinking of the cursor is not eliminated by this service. Hence, depending on the alternation rate selected, a 2-beat frequency may be noticeable. ---------------- 3. ANSI-COMPATIBLE VIDEO FILTER MODULE MS-DOS and IBM PC-DOS files include ANSI.SYS, a console filter driver that mediates a subset of American National Standards Institute (ANSI) standard escape sequences for video functions as well as a supplementary subset for keyboard functions (such as key reprogramming). VIz has a second, independently installable resident module that implements standard ANSI escape sequences to control the console video functions. This ANSI-compatible filter uses less than some 800 additional bytes of RAM when installed. It can be turned off either by uninstalling all the VIz resident modules or by inactivating the filter with switch /A-. The inactive filter can be reactivated with switch /A+. All ANSI operations use BIOS calls. The filter does not provide by itself much acceleration of DOS video I/O as far as ANSI instructions are concerned. Its advantages are small size, the capability of being switched on or off, and its harmonious working with the acceleration module of VIz. To avoid conflicts, VIz will not install its ANSI filter if ANSI.SYS or the utility ANSI.COM (Copyright 1989 Ziff-Davis Corp., version 1.20) is already loaded. The presence of either one can be ascertained via the Status/Usage panel displayed by the command 'VIZ ?┘' from the DOS prompt. -------- The ANSI-compatible filter implements the following subset of ANSI 3.64-1979 standard escape sequences to control console video functions (see your MS/PC DOS documentation of ANSI commands): A. Selection of the foreground and background colors on a color display or the text attributes on a monochrome display system. The sequence syntax is <Esc>[#;...;#m, where # is 30-37 to select a foreground color, 40-47 47 to select a background color, and 0-1, 4-5 or 7-8 to select the text attributes. B. Selection of the video mode (similar to using the MODE command of DOS). The sequence syntax is <Esc>[=#h or <Esc>[=#l, where # is 0-6 or higher (depending on the adapter card in use). C. Selection of word wrapping, i.e. whether lines longer than the width of the screen are truncated. The sequence syntax is <Esc>[?7h or <Esc>[?7l to turn word wrapping ON or OFF, respectively. D. Cursor positioning for the following sequences: <Esc>[r#;c#H - Move to specified row (r#) and column (c#) <Esc>[r#;c#f - Same a previous sequence <Esc>[r#A - Move cursor up by specified number of rows <Esc>[r#B - Move cursor down by specified number of rows <Esc>[c#C - Move forward the specified number of columns <Esc>[c#D - Move backward the specified number of columns <Esc>[s - Store current position of the cursor <Esc>[u - Restore to the position stored by <Esc>[s <Esc>[K - Erase from the cursor to end of the line <Esc>[2J - Clear all rows and home cursor (this sequence preserves current color attribute) Not supported by the filter are the cursor-position-reporting ANSI sequence (<Esc>[r#;c#R) and the supplementary set of sequences used by DOS' ANSI.SYS to permit keyboard reprogramming (i.e. <Esc>[#;'string';3p), a set which is not part of the 1979 ANSI standard. You should thus consider using the filter, instead of ANSI.SYS or ANSI.COM, when interested in using video escape sequences alone, without any keyboard remapping. ---------------- 4. INTERCEPTED INTERRUPTS VIz versions 2.40 and higher do not monitor interrupt 1Ah any longer before attempting to uninstall the residents. The following hardware and software interrupts are intercepted according to the loading configuration: INTERRUPT 8h (system timer): Channel 0 of the 8253/8254 timer chip produces a hardware interrupt (IRQ0), interrupt 8h, about 18.2 times a second that is used by the system time-of- day clock. When the cursor module is installed, switch /Vn (n=0 or 1 to 99) forces the display of the block cursor, either in continuous or alternating manner. Depending on the VIz version (cf. 4.2), cursor shape is implemented via commands using word (16 bits) or byte (8 bits) output. INTERRUPT 10h (video BIOS): The accelerator module of VIz intercepts the ROM BIOS video interrupt, 10h. When the system is in page 0 and a text mode, video acceleration occurs for subfunctions 0h through Eh, except for subfunctions 4h, 7h, Bh, and Ch. INTERRUPT 21h (DOS services): Starting with version 2.0, DOS allows the redirection of the Standard Input (StdIn) and Standard Output (StdOut) console device, permitting programs to send input to or to receive output from other programs. Unless redirected, the StdIn comes from the keyboard and the StdOut goes to the screen. These and some other devices can be addressed by predefined DOS 'file handles' as if they were disk files. A common DOS-mediated technique to send output to the screen is to write to the handle 1 (StdOut) via interrupt 21h, function 40h; in fact, this is the preferred method of DOS-mediated video output for DOS version 2.0 or higher. The accelerator module of VIz also intercepts interrupt 21h. Switch /Z+ re- directs the 21h/40h/1-console stream (StdOut) to the accelerator, resulting in significant accelerations of the DOS video services. The acceleration is not increased by setting the DOS mode to "raw" (see below). Switch /Z- (or default installation) permits the 21h/40h/1-video output to be processed by the CON: device. The redirection of StdOut to VIz does not conflict with the CLS command (as the redirection does not affect interrupt 29h [see section 4.1]). Selection of switch /Z+, however, voids any redirection of the StdOut, including that to the NUL: device (e.g., to avoid some messages), since the 21h/40h-stream is intercepted by VIz before the output can be redirected by DOS. Switch /Z requests are not disregarded when ANSI.SYS, ANSI.COM, or VIz-ANSI filter is active. Notice, however, that the redirection of StdOut by switch /Z+ will conflict with any ANSI command sent to the CON device via standard output calls to interrupt 21h/40h/1. ANSI commands using interrupt 29h are not affected by switch /Z+ (see below). INTERRUPT 29h (fast CON) The ANSI-compatible module of VIz intercepts interrupt 29h, an undocumented feature present in all recent versions of DOS. Int 29h is normally provided by the built-in console device driver of DOS, and consists of a call to the BIOS interrupt 10h. DOS uses int 29h instead of the normal request-passing mechanism to accelerate output to the current CON: device. The ANSI module filters this output. If a request to inactivate the installed ANSI filter is encountered (switch /A-), VIz checks whether the int 29h can be restored to its original memory address. If the revectoring is not possible (i.e. when another resident has also intercepted int 29h), this filter remains partially active in order to handle an ANSI escape sequence generated by COMMAND.COM to clear the screen when a CLS command is detected (see below); other ANSI escape sequences are ignored by the filter and passed to the screen. Hence, when revectoring is possible, switch /A- has the same effect as installing VIz without a switch /A, except that the memory occupied by the ANSI filter is not released; the filter is reactivated by a subsequent call to execute VIz with switch /A+. VIz versions 3.64 and higher do not redirect interrupt 29h to the teletype service of VIz any longer (old switch /X±). 4.1 THE CLS COMMAND AND INTERRUPT 29h The internal console device driver installed during booting handles the CLS as well as int 29h service. The CLS procedure of COMMAND.COM first tests to see if (1) the standard-output handle is associated with a character device driver (bit 7=1), and (2) the driver services int 29h (bit 4=1). If one or both tests fail, or if both tests are successful but the vector for int 29h does not point to the memory segment of the DOS kernel, COMMAND.COM outputs the ANSI escape sequence <Esc>[2J to int 29h; otherwise, it makes a call to int 10h, subfunction 6 of the BIOS to clear the screen. When int 29h cannot be revectored on /A-, the partial driver activity slows down slightly the DOS video output whenever the ASCII character 27 (Esc) is found in the character stream. This partial activity is needed, however, as DOS issues an ANSI escape sequence to clear the screen whenever int 29h has been revectored. Thus, if VIz were not to retain its ANSI driver partially active when revectoring of int 29h is not possible, the DOS escape sequence would be displayed (without clearing the screen) whenever a CLS command was issued. ------------------------------------------------------------------------------ 5. USAGE Syntax: VIZ [/Switches] [;Comments] The switches can be entered from: (1) the DOS command line (COMMAND.COM shell prompt) (2) a batch file (3) a DOS environment string with the format VIZ=/SWITCH1.../SWITCHn Switches can be given in any order. Any character between space and slash [/] can be used as a switch delimiter. Switches are not case sensitive. Switches /A, /B, /C, /D, /I, /M, /P, /R, and /S are "sticky" parameters in the sense that the video change they produce will remain in effect even if VIz is made quiescent or is uninstalled. -------------------------------------------------------------------------- Switches marked with asterisks are available only in registered copies -------------------------------------------------------------------------- - [/?] Status/Usage/Help panels. Switch /? displays a status/usage panel, which shows the status of video I/O services, StdOut stream re-direction, ANSI filter, DOS character processing and the current value of video page | and video mode. When VIz is installed, a brief explanation of the status | of each highlighted service can be obtained by pressing the left or right | (cursor) arrow keys or, when a Microsoft Mouse driver 6.0 or a compatible | driver is already installed, by clicking the mouse over the screen button | marked 'Status.' When video modes higher than n+128 (which do not clear the display buffer when selected [AT and PS/2]) are detected, the mode number is followed by an asterisk; thus video mode 131 is displayed as '3*' in the Status line. | In addition to the status-line panels, the status of some on/off switches | is also shown by a '+' or '-' on the switches menu before a given switch. When switch /? is requested and a EGA or VGA adapter is present, VIz will attempt to read (and save) the contents of the palette registers prior to asserting its own attribute palette for the display. For the EGA, this is attempted by setting up a 'Parameter Save Area' that the EGA BIOS can use to store the contents of the palette registers, and the border (overscan) register, so that these contents can be restored upon exiting the Syntax/ Status panel. If the EGA BIOS fails to store the data, VIz then loads the default palette described below in switch /C; the original palette can be restored by clearing the screen (if VIz had been installed with switch /C enabled) or by resetting the video mode. | The Usage panel lists all program switches; to cycle between the menus of | main and auxiliary switches, press <F2> or <M> (or click one mouse button | on the [Menu] pad). The Help panel provides a summary description of the | program and its switches: Press <F1> or <H> (or click one mouse button on | the [Help] pad) to show the help panel. To return to DOS from any panel, | press <Esc> or <X> (or click one mouse button over the [eXit] pad). From | the Usage panel, a two-button click of the mouse in any position provides | a quick exit to DOS. -------- * [/A±] Installs a resident filter to implement (the video subset of) ANSI escape sequences; installation is aborted if presence of the DOS ANSI.SYS is detected. Although this filter can take advantage of VIz acceleration, it is independent of the accelerator resident component, and its activity can be controlled independently with the following switches: * /A+ Reactivates the filter if installed and inactive, or (if VIz is not installed) installs the resident ANSI filter, and inactivates the remapping of the EGA/VGA palette via /Cn:n, /Cm, or /C+. * /A- Inactivates the filter, if installed and active. It also reactivates a previously active remapping of the EGA/VGA palette. Defaults: /A = /A+ -------- * [/Bn] Selects the color for the screen border in text mode and the back- ground and border color for graphic modes. This color is specified by the Red-Green-Blue mixture value given as 1 or 2-digit number in octal format in the range from 0 to 77o (see Switch /C below). Since the border is notoriously poor in most EGA systems (due to overscan properties), switch /B is not likely to produce an acceptable border with such systems. No defaults. -------- * [/C] Allows changes in the EGA/VGA color palette. This palette, which consists of 16 registers, is used map the video memory data into colors. In EGA-compatible modes of the VGA and in the EGA, where 16 simultaneous colors can be displayed out of a possible 64-color palette, the value in each one of such registers determines the amount of Red, Green, and Blue mixture in the displayed color. This amount can be represented by the data bits <RGBrgb>, where <000rgb> shows the color at 33%, <RGB000> at 66%, and <RGBrgb> at 100% intensity. These bits, and their resultant color, are shown below using both binary (base 1) and octal (base 8) number formats: ┌─────────┬───────┬─────────────┐ │ binary │ octal │ Color │ Since the binary format takes up a ├─────────┼───────┼─────────────┤ lot of space it is more convenient °│ 000 000 │ 00 │ 100% black │ to use the 2-digit octal format to │ 000 001 │ 01 │ 33% blue │ represent an RGB value. The binary │ 000 010 │ 02 │ 33% green │ equivalence of octal numbers is: │ 000 011 │ 03 │ 33% cyan │ │ 000 100 │ 04 │ 33% red │ │ 000 101 │ 05 │ 33% magenta│ 0o = 000000b │ 000 110 │ 06 │ 33% yellow │ 1o = 000001b │ 000 111 │ 07 │ 33% white │ 2o = 000010b ├─────────┼───────┼─────────────┤ 3o = 000011b °│ 001 000 │ 10 │ 66% blue │ 4o = 000100b °│ 010 000 │ 20 │ 66% green │ 5o = 000101b °│ 011 000 │ 30 │ 66% cyan │ 6o = 000110b °│ 100 000 │ 40 │ 66% red │ 7o = 000111b °│ 101 000 │ 50 │ 66% magenta│ 10o = 001000b °│ 110 000 │ 60 │ 66% yellow │ 11o = 001001b °│ 111 000 │ 70 │ 66% white │ 12o = 001010b ├─────────┼───────┼─────────────┤ 13o = 001011b °│ 001 001 │ 11 │ 100% blue │ 14o = 001100b °│ 010 010 │ 22 │ 100% green │ 15o = 001101b °│ 011 011 │ 33 │ 100% cyan │ 16o = 001110b °│ 100 100 │ 44 │ 100% red │ 17o = 001111b °│ 101 101 │ 55 │ 100% magenta│ 20o = 010000b °│ 110 110 │ 66 │ 100% yellow │ etc °│ 111 111 │ 77 │ 100% white │ └─────────┴───────┴─────────────┘ (°) IBM-EGA default color palette Of course, other colors can also be generated when using a different RGB mixture value. For instance, a desaturated (i.e., whitish) RGB sequence is obtained in the octal range 71o through 76o. Those using the utility SPECTRUM.COM (Copyright 1987 Ziff-Davis Publishing Corp.) will recognize the <RGBrgb> octal format as the so-called "SPECTRUM code." This palette control is also enabled (VIz 2.42+) for the monochrome mode of VGA and MCGA adapters to remap color codes into gray-scale values. The following services are available: * /Cn:n To modify the EGA/VGA color palette from the DOS command line, type a 16-number sequence in which numbers must be separated by colons (:) as in the following example: /C03:00:20:30:40:50:01:77:70:11:22:33:44:55:66:76 that represents the default palette colors loaded by VIz when switch /C? is used. When an incomplete sequence is provided, the RGB values are written into the respective palette registers starting from register 0. When a non- numeric value is provided, the palette is not changed. * /Cm Unlike the EGA, when the MCGA and VGA emulate a 16-color text mode for a monochrome display, the palette consists of four groups of four shades of gray. Switch /Cm loads a palette where the gray-scale values increase uniformly with increasing attribute values. The monochrome palette corresponds to the command: /C00:50:01:31:61:12:42:03:43:04:44:05:55:26:07:77 Switch /Cm can also be used with CGA monochrome displays (e.g., laptops) to translate color attributes into gray- scale values. /C? This service provides a display of the palette registers and the corresponding RGB mixture in octal format. It is possible to alter the RGB mixture of any register simply by pressing <R>, <G>, or <B> and then <> or <>. These arrows cycle through 0%, 33%, 66%, and 100% intensity of the respective RGB component. The actual RGB mixture of the selection is also shown on a graph. Press the right or left arrow to cycle through the registers, and <HOME> to go to register 0 or <END> to go to register 15. Press <ENTER> to save the current palette, <ESC> to quit the service without any palette changes, <DEL> to reject any change and to restart the service, and the indicated function keys to load several available palettes. * /C- Use to inactivate the implementation of EGA/VGA palette changes via VIz. The video attributes remain unchanged until the a video operation reloads the palette, e.g. a video mode change. Switch /A+ also turns off remapping of the palette. * /C+ Use to reactivate the implementation of EGA/VGA palette changes via VIz; it reloads the last color palette that was selected via VIz. Switch /A- reactivates remapping if remapping was in effect prior to an /A+ request. Defaults: /C = /C+. The selected EGA/VGA palette changes are asserted (i.e. the palette is re- loaded with the selected RGB values) each time that a video mode change or a video font change (int 10h functions 5h and 11h) is requested and VIz is active (i.e., no /Q switch, graphics mode, or video page other than 0). To preserve the small size of Viz, there is no hotkey pop-up service. If a program changes the palette when executed, the RGB mix values selected via VIz cannot be asserted except by shelling to DOS and invoking VIz with the switch /C+ to reload the palette or triggering a video mode/font change. -------- * [/Dn] Adjusts brightness of screen (VGA card only); the brightness change step is specified by the sign and value of number <n> between -63 and +63. Use of a high negative or positive number results in an unreadable screen. Requesting /D0 results in restoration of the screen to its default setting (as dictated by the manual controls of the video monitor). Defaults: /D = = /D+1; /D1 = /D+1. -------- * [/E] Creates the DOS environment string VIZ=/SWITCH1.../SWITCHn, in which SWITCH1...SWITCHn are the switches specified when VIz is executed from the DOS command line. When the string VIZ= already exists, the switch updates the string contents. (Although the switch is incorporated into the string contents, its presence is ignored when VIz uses such string as input.) Switch /E modifes the global environment whether the resident shell is the initial copy of COMMAND.COM (global environment) or a secondary one (local environment). See section 5.1 for more details. No defaults. -------- * [/F] If VIz detects an EGA or VGA adapter, switch /F toggles between 25- row (EGA/VGA) and 43-row (EGA) or 50-row (VGA) displays. (When an EGA/VGA adapter is found, VIz also selects the alternate BIOS print-screen service to avoid the default ROM-BIOS print-screen routine that works with 25 rows only.) In 25-row displays, VIz uses a 8x14 font for EGA or a 9x16 font for VGA. Fonts with more than 25 rows can be loaded only if the current video page is between page 0 and 3 (see switch /S for printing screens with more than 25 rows). No defaults. -------- * [/Gn] Selects frequency in Hertz (cycles per second) of 55-ms bell tones. Values between 25 Hz and 5,000 Hz are accepted. Values below 25 become 25 Hz and above 5,000 become 5,000 Hz; use of more than 4 digits results in a reading of the 4 least significant digits (i.e. 50,000 Hz is read as 0000, triggering the use of 25 Hz). Defaults: /G = /G440. (Most computer speakers work properly only in the range between 100 Hz and 3,000 Hz. Frequencies for the octave starting at middle C are: C = 523.3, D = 587.3, E = 659.3, F = 698.5, A = 880.0, and B = 987.7 Hz. Frequencies at higher [lower] octaves increase [decrease] approximately by a factor of 2 per octave change from the above values.) The tones always last 55 ms (one tick of the 8253/8254 timer chip). Since the tones are forced to begin at the start of a 55-ms tick period, stacked calls to the bell (i.e. 'ECHO ^G^G^G^G^G^G') will result in a distinctive, staccato burst due to intervening, silent 55-ms tick periods. -------- * [/I±] Toggles blinking (/I-) and intense (/I+) background colors whenever the background attribute corresponds to a value between 8 and F (bit 7 on) in the selection of screen foreground/background color. No defaults. -------- * [/L] Instructs the program to load its resident module(s) in high memory between 640 kb and 1,024 kb, i.e., below the 1 Mb boundary of conventional RAM but above the RAM area normally controlled by DOS. Switch /L requires that an XMS manager (XMM) complying with the specifications of XMS 2.0 has been previously installed and that a free upper memory block (UMB) of less than 2 kb is available. The XMM must support functions 10h (Allocate UMB) and 11h (Free UMB). Unlike the high-memory loading provided by 386 memory managers, the required size of the free UMB is that of the resident(s) and not that of the entire VIz program; an additional 64 bytes are used by XMS for the UMB allocation. (See High Memory Installation section.) Defaults: Low-memory installation if any error is found during high-memory loading. -------- * [/Mn] Selects the video mode specified by a number <n> in the range of 0 through 99; note that there is no checking that the selected mode is valid for the adapter. No defaults. -------- * [/N±] Messages dealing with nonfatal operations are either not displayed (/N+), as if they had been sent to the NUL device, or (normally) displayed via the StdOut device (/N-), which can be redirected if switch /Z+ has not been selected. Since VIz gives a beep when a command error is detected, switch /N- should need to be used only after such a beep to display the error message again. Note that the installing, uninstalling and fatal-operation messages of VIz cannot be redirected and are always displayed. The status of operation can be monitored in batch files with ERRORLEVEL commands. Defaults: /N = /N+. -------- * [/Pn] Selects the video page specified by a number (n) in the range of 0 to 7 for EGA/VGA with 25-row font, or 0 to 3 for CGA and 43/50-row EGA/VGA adapter. No defaults. -------- - [/Q] Quiescent. Switch /Q forces VIz to a 'quiet' mode; although still resident, VIz will not provide video acceleration. The overhead time for having VIz in quiescent mode is 2% or less of that without VIz. Note that even when quiescent or during graphics video mode, VIz still monitors the BIOS video interrupt to check for page or mode change requests. Switch /Q | disables video BIOS and StdOut (/Z+) acceleration, but does no affect the | operation of the ANSI filter (/A+). -------- * [/R±] Forces the StdOut character device to normal text output mode [R-] or 'raw' mode [R+]. In normal mode output, the DOS kernel builds a device request header for a single character output, makes a Control-C check, and passes the request to the device; if there is no error, the buffer pointer and character count are updated, and this process is repeated until either an end-of-file character (ASCII 26, Ctrl-Z) is found or all characters are processed. Tabs (ASCII 9) are expanded to 8 spaces. In raw or binary mode, however, DOS does not filter the stream for control characters, but a single request header is passed to the device. Depending on the DOS version, the DOS-mediated video output is faster in raw mode by factor of about 1.40 (a much larger factor is provided by switch /Z+). No defaults. NOTE: When using 'raw' DOS mode as the default condition, be sure to set BREAK=ON in the CONFIG.SYS file to facilitate Ctrl-Break detection Some utilities set the DOS mode to 'raw' when executed and then change the mode to normal when they finish, irrespective of the mode encountered when they were executed. Hence, repeated use of switch /R+ may be necessary to maintain the raw character processing mode. -------- * [/S±] Inactivates [S-] or reactivates [S+] the BIOS Print Screen function triggered by pressing the <PrtSc> key. This is useful when the keys of the number pad are used often, and the chance of triggering an unwanted screen print is commensurably high. If /S+ or /S-, or simply /S, is requested at the time of the installation, VIz selects via a BIOS call the alternate print-screen service in the EGA/ VGA card BIOS extension that works properly if the screen length is not 25 lines (when the card is an EGA or VGA adapter). This alternate service is needed when 43/50 lines are to be used, since the ROM BIOS default service only prints 25 lines. NOTE: Some EGA cards do not work properly when the alternate print-screen service is selected. If selecting switch /S± at installation results in a print-screen malfunction, first install VIz without selecting /S+, /S-, or /S, and then select the switch in a subsequent execution. Defaults: /S = enable BIOS alternate print-screen service -------- - [/U] Uninstall. Switch /U uninstalls the resident components of VIz if the original interrupt vector 10h (and 29h, if the ANSI resident has also been installed) has not been changed. As with any other resident, do not uninstall VIz after another resident has been installed since the machine is likely to crash. Starting with version 2.20, VIz can be identified by name in low-memory- usage maps. Although VIz removes its own copy of the DOS' environment at at loading time (to minimize resident size), 'VIzxxx' will appear in the in the listings of these maps irrespective of the actual contents of the DOS command line at the time of VIz installation. For instance, the 386 version of VIz (accelerator module only) will be listed by MAPMEM.COM of Turbo Power Software as: PSP blks bytes owner command line hooked vectors ----- ---- ----- -------- ------------------- --------------- xxxx 1 928 N/A VIz412 10 21 if VIz is installed in DOS memory. However, if VIz is installed in high conventional memory via switch /L, it will be listed only as: PSP blks bytes owner command line hooked vectors ----- ---- ----- -------- ------------------- --------------- xxxx 1 928 N/A (Some other memory mapping utilities may fail to list this UMB separately lumping it instead with other allocated blocks.) -------- - [/V] Forces a display of an alternating full-block-and-thin-line cursor [Vn, n=1 to 99] or of a continuous full block [Vn, n=0], makes the cursor invisible [V-], or allows display of the normal cursor [V+]. Switches /Vn and /V- produce changes of cursor type that can be reversed with /V+. Due to a potential BIOS conflict, switch /V- is ignored at installation time; to make an invisible cursor, first use /V+ or /Vn and then /V-. Defaults: /V = /V+. NOTE: The cursor resident component is not loaded unless VIz is installed with the switch /V+ or /Vn, and cannot be loaded after installation of the resident. -------- - [/Z±] Directs video output mediated via interrupt 21h, fn. 40h (write to device [StdOut]) to the console driver [Z-], or to the accelerator module of VIz [Z+]. Defaults: Null or /Z = /Z-. Switch /Z+ provides a significant acceleration of video output for DOS-2+ services and many other utilities using the write-to-StdOut function. See above for conflicts with StdOut redirection. Z+ processing uses an 8- space tab expansion (which is the standard expansion used by DOS). This, however, conflicts with the 4-space tab expansion used by the DOS command 'DIR' for its switch /W. -------- Comments may be added in the DOS command line invoking VIz after the desired switches. The comments, which may be useful in clarifying batch files, must be preceded by a semicolon (;), and are ignored by VIz. NOTE: Do not use the DOS redirection (<>) and pipe (|) characters in these comments as DOS will attempt to implement the implied redirection or pipe request. ------------------------------------------------------------------------------ 5.1 ENVIRONMENT VARIABLE 'VIZ' Starting with VIz version 3.63, when VIz is executed without any arguments from either the DOS command line or a batch file, the program switches can be specified via a DOS environment variable 'VIZ' having the format: VIZ=/SWITCH1/SWITCH2..../SWITCHn Up to 128 characters are allowed after the equal sign. There cannot be any spaces between switches; use slash as a separator. The string can be placed in the DOS environment block via the SET command or via switch /E. While the SET command modifies the default environment block, whether it is the global or a local one, switch /E always modifies the global environment block (even when VIz is executed via a secondary copy of COMMAND.COM, as in the case of 'shelling to DOS' from inside an application). Note that local environment blocks (i.e. a secondary COMMAND) are only a copy of the master global block and lack sufficient room to increase the length of a variable; hence, when the default block is a local one, switch /E does not modify it. In contrast, when reading the environment variable, the program always uses the default environment block. NOTE: See the file DOS_ENV.TXT, distributed in this release, for a more detailed description of the DOS environment block. A recommended use of the environment string is to specify the default /Cn:n configuration (e.g. /C03:00:20:30:40:50:01:77:70:11:22:33:44:55:66:76) that can be restored simply by executing VIz without any arguments after the RBG EGA/VGA palette has been changed. ---------------- 5.2 DOS ERRORLEVEL Starting with version 3.10, VIz passes to DOS execution status values that can be tested in batch files via the ERRORLEVEL command; the following are values for version 4.02 or higher: Value Condition ----- -------------------------------------- 255 Cyclical Redundancy Check failure 254 CPU type does not support the 386 or 286 version 253 Not enough memory to execute /C? or /? 252 Unable to remove resident from memory 251 Invalid cursor (switch /Vn) request 250 Invalid ANSI (switch /A) request 128 XMM not installed or XMS error in UMB load 64 Incomplete color palette data list 32 Invalid color palette datum 16 Invalid video font for adapter and/or page 8 Invalid video mode request 4 Invalid video page for adapter and/or font 2 Invalid video adapter for the request 1 Unknown or invalid switch request 0 Succesful execution Note that some errorlevel conditions in the range between 1 and 128 may be additive, and the errorlevel output may represent the sum of their values. ---------------- 6.0 INSTALLATION It is recommended that VIz be installed before other resident programs also using the BIOS video interrupt 10h. Due to the nature of some of the video functions served, VIz often will not daisy chain the interrupt-10h requests to residents located down the intercepted interrupt-10h chain. In order for these residents to receive interrupt-10h data, they must be installed after VIz has been installed; thus, it is convenient to install VIz early in your AUTOEXEC.BAT file. Keep in mind that the larger the number of additional residents, the slower the absolute video acceleration times provided by VIz. This is because the int-10h request has to be processed by each element in the interrupt chain. One way to minimize the problem is to install a minimum number of residents via the AUTOEXEC.BAT and, before executing a given application, install any additional resident via a batch file that also executes the application and removes the residents upon the completion of the task. (VIz itself may fall in this transient category.) If you intend to make occasional use of the ANSI-compatible filter, without removing the resident ANSI component from memory, VIz may be installed just as decribed above. However, if you want to remove the ANSI component after a given ANSI-oriented task, then VIz must be the last resident to have been installed prior to such a removal. ANSI.SYS or ANSI.COM should not be loaded in order to use the ANSI resident of VIz. Notice that if an ANSI filter is active and VIz is switched to its 'fast DOS' mode (/Z+), this filter is likely to be unable to process escape sequences, unless the sequences are sent directly to the CONsole device via interrupt 29h instead of via DOS interrupt 21h. 6.1 RESIDENT SIZE Resident sizes obtained for various installation switches are listed below. The values are in bytes to the nearest 16-byte ('paragraph') multiple: VIz 4.12 /Z+ /V+ /A+ ----------------------------------- 386+ 928 1008 1696 286+ 896 976 1680 086+ 912 992 1696 6.2 HIGH-MEMORY RESIDENT INSTALLATION DIRECT UMB LOADING Starting with version 4.02, VIz can load itself directly into high memory (RAM addresses between 640 kb and 1,024 kb) via switch /L. Such a loading is mediated by an XMS manager (XMM) version 2.0, such as the driver HIMEM .SYS (Microsoft), which must be installed prior to VIz loading. Some 386- memory managers (386^MAX version 4.09 and QEMM version 5.11, for example) provide XMS support as well. All XMMs require DOS version 3.0 or later. For the loading to be successful, an upper memory block (UMB) of the size of the VIz resident(s), plus an additional 48-byte block used by the XMM, must be available. LOADING VIA 386-MEMORY MANAGERS VIz can also be loaded into high memory via 386-specific memory managers, provided that there is enough high-memory for the actual size of VIz plus the additional memory that is required by the loading utility. VIz is a compressed file that expands when loaded. The difference between the loaded and the directory size of VIz may produce conflicts with high- memory loading utilities that fail to measure the actual size of the file being loaded. If there is not enough high-DOS memory to permit expansion, but there is enough memory for the nominal directory size, such utilities will load the compressed program, whose subsequent expansion is likely to overwrite adjacent code and crash the computer. Note that when switch /? or /C? has been selected, an additional 4,300 bytes of RAM are needed. Further, even when the proper size is specified and available, some high- memory loading programs for 386 systems may become corrupted when loading into high memory compressed files of the type of VIz. 6.3 HIGH-MEMORY RESIDENT UPDATING Starting with version 3.40, a high-memory loading utility is not required to update the resident component of VIz, when this resident was installed in the first megabyte of memory (286+ CPU). Such updates can be made via normal calls from the DOS command line or batch-file calls. This obviates a major restriction in using high memory installation, namely the need to keep enough free high memory to load an entire program only to update its small resident component. 6.4 HIGH-MEMORY RESIDENT REMOVAL When VIz has been installed in high memory directly via switch /L, it can be removed directly from memory via switch /U from the DOS command line. When a high-memory installation was mediated by a memory manager, Viz can be removed with switch /U directly from the command line or after opening the high memory with the memory manager. When the resident is removed via such a manager, notice that some of these utilities warn that a "resident installation has failed." Such warnings are harmless and may be ignored. ------------------------------------------------------------------------------ 7. ERROR MESSAGES 7.1 "CRC error ─ Execution aborted" A failure of 32-bit cyclical redundancy check was encountered when VIz was executed. -------- 7.2a "This CPU cannot execute 286+ code ─ VIz aborted" 286+ versions of VIz cannot be executed in 8088, 8086, or (most) 80186 CPU machines. -------- 7.2b "This CPU cannot execute 386+ code ─ VIz aborted" 386+ versions of VIz cannot be executed in 8088, 8086, 80186, or 80286 CPU machines. -------- 7.3 "Needs DOS 2.10 or higher ─ Execution aborted" The program requires an MS-DOS/IBM-PC DOS version equal to or greater than 2.10 for proper execution. -------- 7.4 "Installed - Enter 'VIz /?' for Status/Help panel" VIz was successfully executed and the resident(s) installed. -------- 7.5 "A logical device named 'CON' is already installed" "Loading of the resident ANSI filter is cancelled." A logical driver with the device name CON was detected during installation with switch /A+ selected; in most cases this character device is ANSI.SYS. The resident ANSI filter of VIz is not installed. -------- 7.6 "Updated" The relevant resident parameters of VIz were successfuly updated. -------- 7.7 "Interrupt XXh has been revectored ─ Cannot uninstall" "Remove revectoring or inactivate with switches /Q/A-" The indicated interrupt vector (segment:offset) has been changed since its interception during the installation. VIz hooks interrupts 08h, 10h, 21h, and 29h (hexadecimal); if more than one interrupt vector has changed, only the first one is shown. -------- 7.8 "Not enough memory for display processing" When switch /C? or /? is selected, VIz first releases any additional memory and then requests to DOS the allocation of 4300 bytes for video processing. The message is displayed if this memory is not available (other services or functions can still be executed). -------- 7.9 "Invalid switch /Xx ─ Request disregarded" An invalid switch designator (X) or switch parameter (x) was passed to VIz. -------- 7.10 "Cannot add resident modules after VIz installation:" "Uninstall residents and reinstall with switch '/A+'" Switch /A+ was requested after VIz was installed without the resident ANSI filter. Viz needs to be uninstalled and then reinstalled with the switch. -------- 7.11 "Cannot add resident modules after VIz installation:" "Uninstall residents and reinstall with switch '/Vn'" Switch /Vn was requested after VIz was installed without the laptop cursor resident. Viz needs to be uninstalled and then reinstalled with the switch. -------- 7.12 "Invalid page request" A page greater than the maximum page allowed by the video adapter and the current video font was requested. The CGA supports four 80x25 text pages (0-3). The EGA, MCGA, and VGA support eight 80x25 pages (0-7), or 4 pages when 80x43 (EGA), 80x40 (MCGA), or 80x50 (VGA) font displays are used. -------- 7.13 "Only pages 0-3 can be used with 43/50-row fonts" A video page (4 through 7) incompatible with the video font was requested (see 7.11). -------- 7.14 "Invalid mode request" A video mode incompatible with the (active) video adapter was requested. -------- 7.15 "Invalid adapter request" An operation or service incompatible with the (active) video adapter was requested. -------- 7.16 "Incomplete RGB data ─ Partial palette update" An incomplete list of EGA/VGA palette RGB mixtures was provided. Only the data provided were updated. -------- 7.17 "Invalid RGB datum ─ Palette unchanged" An invalid RGB mixture datum was provided in an EGA/VGA palette list. The data of the palette were not changed. -------- 7.18 "Invalid bell frequency" A bell tone frequency less than 25 Hz or more than 5000 Hz was requested. -------- 7.19 "ANSI filter not yet installed" Switch /A- was requested when the ANSI filter had not been installed. -------- 7.20 "Uninstalled" VIz resident modules were successfuly deallocated from memory. -------- 7.21 "Failed to detect presence of an XMS manager (XMM)" VIz failed to determine presence of a driver compatible with the Extended Memory Specification (XMS) version 2.0 and the requested high-memory load (/L) defaulted to a normal low-memory installation. -------- 7.22 "XMM failed to allocate upper memory block [XMS error: XXh]" The XMS manager did not allocate the requested UMB. One of the following XMS error codes would be expected: 00h - Allocated UMB smaller than requested size. 80h - Function is not implemented. 8Eh - General driver error occurred. 8Fh - Unrecoverable driver error occurred. B0h - Smaller UMB is available. B1h - No UMBs are available. B2h - UMB segment number is invalid. -------- 7.23 "XMM failed to free upper memory block [XMS error: XXh]" The XMS manager did not free the allocated UMB. (See above for XMS error codes.) -------- 7.24 "Not enough room in DOS environment block" There is insufficient room in the DOS environment block for the requested VIZ= environmental variable; this may be due to the use of a small block, which can be expanded as described in the file DOS_ENV.TXT. ------------------------------------------------------------------------------ SINGLE USER (BBS-DISTRIBUTED) LICENSE AGREEMENT REGISTRATION These programs and the documentations (the "software") are the copyrighted property of FM de Monasterio (the "author"), who provides the software and licenses its use. Neither the title to nor ownership of this software are transferred to you by such a license, and both are retained by the author. All rights are reserved. The software is user-supported; the enclosed release, although lacking the options marked by asterisks, is a fully usable program. You may test this release for (in)compatibilities with your system, but after the testing is completed you are requested to order a registered release of this software from the address below. Alternatively, to continue use of this unregistered copy, send to the same address a US$5.00 check marked "For Deposit Only," and payable to "PATIENT CARE FUND, CHILDREN'S HOSPITAL" of Washington, DC. Unregistered users who donate to this fund may legally keep such a copy under the injunctions and limitations described below. A form needed for the registration or upgrade of this software is provided in the file VIZ.REG. Refer all inquiries about the software to: FM de Monasterio P.O. Box 219 Cabin John, MD 20818-0219 LICENSE Upon registration you receive a non-exclusive, non-transferable license to use the software. Two types of license are available: Single User License: Upon registration/upgrade you are granted a nontransferable license to use the software in a single computer at a time. You may transfer the software physically to another computer provided that the software is then not used on more than one computer at any time. Site/10-Computer License: Upon registration/upgrade you are granted a nontransferable license to use the software in a single site or a set of sites provided that the software is not used in more than ten computers at any time and that such computers are located exclusively within the registered site(s). UPGRADES Within the same major version: Registered software users can upgrade free of charge within the same major version (e.g., 2.00 through 2.99). Outside the same major version: Registered users can upgrade for half the the license fee for a different version of the software. To upgrade send a self-addressed stamped diskette mailer with the original 360 kb diskette to the address above, along with the upgrade form. SUPPORT Limited technical support is provided to registered users. If you discover a problem, please try to replicate it under the same conditions and, then, in the absence of other resident programs. (Changes in the order residents are installed sometimes solve conflicts.) If the problem can be replicated please write at the address above providing: - Your name and address. - Program version number (see the Syntax/Help panel). - Computer model and configuration, and hardware used. - A sufficiently detailed description of the problem. - A list of resident and nonresident programs in use, and their sequence of loading into memory. Messages may be left c/o Sysop at: The DC Information Exchange BBS ~~~ 202-433-6639, Sysop: Bill Walsh (2400+ baud). INJUNCTIONS You may distribute this software via magnetic and/or electronic means, but you are specifically prohibited from: - Charging fees or asking donations in exchange of or payment for copies of the software. - Distributing this software with commercial products without the written permission from the author. - Distributing this software via a for-profit organization or group, either alone or with other software. The unauthorized copying, decompiling or disassembling of this software is prohibited; any other use of this software is prohibited without a written permission in advance from the author. LIMITED WARRANTY The author-copyright owner warrants for a period of thirty (30) days from the date of delivery that, under normal use and without any modification, the programs substantially conform to the accompanying specifications and that the documentation is substantially complete and contains information the author deems necessary to use the programs. If, during the thirty-day period, a demonstrable defect in the programs, magnetic medium upon which they are distributed, or documentation should appear, you may return this software for repair or replacement, at the author's option. If the defect cannot be repaired, or the software replaced with functionally equivalent software, within sixty (60) days of the author's receipt of the defective software, then you shall be entitled to a full refund of the license fee, but not of the mailing/handling costs described in the registration form. All other warranties of any kind, either express or implied,including but not limited to the implied warranties of merchantability and fitness for for as a particular purpose, are expressly excluded. The author cannot and does not warrant that any function contained in the programs will meet your requirements, or that the operation will be error free. The entire risk as to the software performance or quality, or both, is solely with the user, and not with the author. LIMITATION OF REMEDIES You assume responsibility for the selection of the program to achieve your intended results, and for the installation, use, and results obtained from the software. The author makes no warranty, either implied or expressed, including with- out limitation any warranty with respect to this software documented here, its quality, performance, or fitness for a particular purpose. In no event shall the author be liable to you for damages, whether direct or indirect, incidental, special, or consequential arising out the use of or any defect in the software, even if the author has been advised of the possibility of such damages, or for any claim by any other party. The author's entire liability, and your exclusive remedy shall be: (1) the replacement of an original software diskette not meeting the above Limited Warranty and which is returned to the author along with proof of purchase, or (2), if the author is unable to deliver a replacement diskette which is free of defects, you may terminate the License Agreement by returning this software and the corresponding license fee will be returned. GENERAL By using the software, you acknowledge (1) to have read and understood all parts of this document and (2) to have agreed with and accepted all of its provisions without any reservation. ------------------------------------------------------------------------------ [END]